home *** CD-ROM | disk | FTP | other *** search
/ SGI Freeware 1999 August / SGI Freeware 1999 August.iso / dist / fw_xemacs.idb / usr / freeware / lib / xemacs-20.4 / info / lispref.info-34.z / lispref.info-34
Encoding:
GNU Info File  |  1998-05-21  |  49.6 KB  |  1,151 lines
  1. This is Info file ../../info/lispref.info, produced by Makeinfo version
  2. 1.68 from the input file lispref.texi.
  3.  
  4.    Edition History:
  5.  
  6.    GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
  7. Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
  8. Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
  9. XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
  10. GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
  11. Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
  12. Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
  13. Reference Manual (for 19.15 and 20.1, 20.2) v3.2, April, May 1997
  14.  
  15.    Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
  16. Foundation, Inc.  Copyright (C) 1994, 1995 Sun Microsystems, Inc.
  17. Copyright (C) 1995, 1996 Ben Wing.
  18.  
  19.    Permission is granted to make and distribute verbatim copies of this
  20. manual provided the copyright notice and this permission notice are
  21. preserved on all copies.
  22.  
  23.    Permission is granted to copy and distribute modified versions of
  24. this manual under the conditions for verbatim copying, provided that the
  25. entire resulting derived work is distributed under the terms of a
  26. permission notice identical to this one.
  27.  
  28.    Permission is granted to copy and distribute translations of this
  29. manual into another language, under the above conditions for modified
  30. versions, except that this permission notice may be stated in a
  31. translation approved by the Foundation.
  32.  
  33.    Permission is granted to copy and distribute modified versions of
  34. this manual under the conditions for verbatim copying, provided also
  35. that the section entitled "GNU General Public License" is included
  36. exactly as in the original, and provided that the entire resulting
  37. derived work is distributed under the terms of a permission notice
  38. identical to this one.
  39.  
  40.    Permission is granted to copy and distribute translations of this
  41. manual into another language, under the above conditions for modified
  42. versions, except that the section entitled "GNU General Public License"
  43. may be included in a translation approved by the Free Software
  44. Foundation instead of in the original English.
  45.  
  46. 
  47. File: lispref.info,  Node: Fonts,  Next: Colors,  Prev: Faces,  Up: Faces and Window-System Objects
  48.  
  49. Fonts
  50. =====
  51.  
  52.    This section describes how to work with font specifier and font
  53. instance objects, which encapsulate fonts in the window system.
  54.  
  55. * Menu:
  56.  
  57. * Font Specifiers::        Specifying how a font will appear.
  58. * Font Instances::        What a font specifier gets instanced as.
  59. * Font Instance Names::        The name of a font instance.
  60. * Font Instance Size::        The size of a font instance.
  61. * Font Instance Characteristics:: Display characteristics of font instances.
  62. * Font Convenience Functions::    Convenience functions that automatically
  63.                   instance and retrieve the properties
  64.                   of a font specifier.
  65.  
  66. 
  67. File: lispref.info,  Node: Font Specifiers,  Next: Font Instances,  Up: Fonts
  68.  
  69. Font Specifiers
  70. ---------------
  71.  
  72.  - Function: font-specifier-p OBJECT
  73.      This predicate returns `t' if OBJECT is a font specifier, and
  74.      `nil' otherwise.
  75.  
  76. 
  77. File: lispref.info,  Node: Font Instances,  Next: Font Instance Names,  Prev: Font Specifiers,  Up: Fonts
  78.  
  79. Font Instances
  80. --------------
  81.  
  82.  - Function: font-instance-p OBJECT
  83.      This predicate returns `t' if OBJECT is a font instance, and `nil'
  84.      otherwise.
  85.  
  86.  - Function: make-font-instance NAME &optional DEVICE NOERROR
  87.      This function creates a new font-instance object of the specified
  88.      name.  DEVICE specifies the device this object applies to and
  89.      defaults to the selected device.  An error is signalled if the
  90.      font is unknown or cannot be allocated; however, if NOERROR is
  91.      non-`nil', `nil' is simply returned in this case.
  92.  
  93.      The returned object is a normal, first-class lisp object.  The way
  94.      you "deallocate" the font is the way you deallocate any other lisp
  95.      object: you drop all pointers to it and allow it to be garbage
  96.      collected.  When these objects are GCed, the underlying X data is
  97.      deallocated as well.
  98.  
  99. 
  100. File: lispref.info,  Node: Font Instance Names,  Next: Font Instance Size,  Prev: Font Instances,  Up: Fonts
  101.  
  102. Font Instance Names
  103. -------------------
  104.  
  105.  - Function: list-fonts PATTERN &optional DEVICE
  106.      This function returns a list of font names matching the given
  107.      pattern.  DEVICE specifies which device to search for names, and
  108.      defaults to the currently selected device.
  109.  
  110.  - Function: font-instance-name FONT-INSTANCE
  111.      This function returns the name used to allocate FONT-INSTANCE.
  112.  
  113.  - Function: font-instance-truename FONT-INSTANCE
  114.      This function returns the canonical name of the given font
  115.      instance.  Font names are patterns which may match any number of
  116.      fonts, of which the first found is used.  This returns an
  117.      unambiguous name for that font (but not necessarily its only
  118.      unambiguous name).
  119.  
  120. 
  121. File: lispref.info,  Node: Font Instance Size,  Next: Font Instance Characteristics,  Prev: Font Instance Names,  Up: Fonts
  122.  
  123. Font Instance Size
  124. ------------------
  125.  
  126.  - Function: x-font-size FONT
  127.      This function returns the nominal size of the given font.  This is
  128.      done by parsing its name, so it's likely to lose.  X fonts can be
  129.      specified (by the user) in either pixels or 10ths of points, and
  130.      this returns the first one it finds, so you have to decide which
  131.      units the returned value is measured in yourself ...
  132.  
  133.  - Function: x-find-larger-font FONT &optional DEVICE
  134.      This function loads a new, slightly larger version of the given
  135.      font (or font name).  Returns the font if it succeeds, `nil'
  136.      otherwise.  If scalable fonts are available, this returns a font
  137.      which is 1 point larger.  Otherwise, it returns the next larger
  138.      version of this font that is defined.
  139.  
  140.  - Function: x-find-smaller-font FONT &optional DEVICE
  141.      This function loads a new, slightly smaller version of the given
  142.      font (or font name).  Returns the font if it succeeds, `nil'
  143.      otherwise.  If scalable fonts are available, this returns a font
  144.      which is 1 point smaller.  Otherwise, it returns the next smaller
  145.      version of this font that is defined.
  146.  
  147. 
  148. File: lispref.info,  Node: Font Instance Characteristics,  Next: Font Convenience Functions,  Prev: Font Instance Size,  Up: Fonts
  149.  
  150. Font Instance Characteristics
  151. -----------------------------
  152.  
  153.  - Function: font-instance-properties FONT
  154.      This function returns the properties (an alist or `nil') of
  155.      FONT-INSTANCE.
  156.  
  157.  - Function: x-make-font-bold FONT &optional DEVICE
  158.      Given an X font specification, this attempts to make a "bold" font.
  159.      If it fails, it returns `nil'.
  160.  
  161.  - Function: x-make-font-unbold FONT &optional DEVICE
  162.      Given an X font specification, this attempts to make a non-bold
  163.      font.  If it fails, it returns `nil'.
  164.  
  165.  - Function: x-make-font-italic FONT &optional DEVICE
  166.      Given an X font specification, this attempts to make an "italic"
  167.      font.  If it fails, it returns `nil'.
  168.  
  169.  - Function: x-make-font-unitalic FONT &optional DEVICE
  170.      Given an X font specification, this attempts to make a non-italic
  171.      font.  If it fails, it returns `nil'.
  172.  
  173.  - Function: x-make-font-bold-italic FONT &optional DEVICE
  174.      Given an X font specification, this attempts to make a
  175.      "bold-italic" font.  If it fails, it returns `nil'.
  176.  
  177. 
  178. File: lispref.info,  Node: Font Convenience Functions,  Prev: Font Instance Characteristics,  Up: Fonts
  179.  
  180. Font Convenience Functions
  181. --------------------------
  182.  
  183.  - Function: font-name FONT &optional DOMAIN
  184.      This function returns the name of the FONT in the specified
  185.      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
  186.      is normally a window and defaults to the selected window if
  187.      omitted.  This is equivalent to using `specifier-instance' and
  188.      applying `font-instance-name' to the result.
  189.  
  190.  - Function: font-truename FONT &optional DOMAIN
  191.      This function returns the truename of the FONT in the specified
  192.      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
  193.      is normally a window and defaults to the selected window if
  194.      omitted.  This is equivalent to using `specifier-instance' and
  195.      applying `font-instance-truename' to the result.
  196.  
  197.  - Function: font-properties FONT &optional DOMAIN
  198.      This function returns the properties of the FONT in the specified
  199.      DOMAIN, if any.  FONT should be a font specifier object and DOMAIN
  200.      is normally a window and defaults to the selected window if
  201.      omitted.  This is equivalent to using `specifier-instance' and
  202.      applying `font-instance-properties' to the result.
  203.  
  204. 
  205. File: lispref.info,  Node: Colors,  Prev: Fonts,  Up: Faces and Window-System Objects
  206.  
  207. Colors
  208. ======
  209.  
  210. * Menu:
  211.  
  212. * Color Specifiers::        Specifying how a color will appear.
  213. * Color Instances::        What a color specifier gets instanced as.
  214. * Color Instance Properties::    Properties of color instances.
  215. * Color Convenience Functions::    Convenience functions that automatically
  216.                   instance and retrieve the properties
  217.                   of a color specifier.
  218.  
  219. 
  220. File: lispref.info,  Node: Color Specifiers,  Next: Color Instances,  Up: Colors
  221.  
  222. Color Specifiers
  223. ----------------
  224.  
  225.  - Function: color-specifier-p OBJECT
  226.      This function returns non-`nil' if OBJECT is a color specifier.
  227.  
  228. 
  229. File: lispref.info,  Node: Color Instances,  Next: Color Instance Properties,  Prev: Color Specifiers,  Up: Colors
  230.  
  231. Color Instances
  232. ---------------
  233.  
  234.    A "color-instance object" is an object describing the way a color
  235. specifier is instanced in a particular domain.  Functions such as
  236. `face-background-instance' return a color-instance object.  For example,
  237.  
  238.      (face-background-instance 'default (next-window))
  239.          => #<color-instance moccasin 47=(FFFF,E4E4,B5B5) 0x678d>
  240.  
  241.    The color-instance object returned describes the way the background
  242. color of the `default' face is displayed in the next window after the
  243. selected one.
  244.  
  245.  - Function: color-instance-p OBJECT
  246.      This function returns non-`nil' if OBJECT is a color-instance.
  247.  
  248. 
  249. File: lispref.info,  Node: Color Instance Properties,  Next: Color Convenience Functions,  Prev: Color Instances,  Up: Colors
  250.  
  251. Color Instance Properties
  252. -------------------------
  253.  
  254.  - Function: color-instance-name COLOR-INSTANCE
  255.      This function returns the name used to allocate COLOR-INSTANCE.
  256.  
  257.  - Function: color-instance-rgb-components COLOR-INSTANCE
  258.      This function returns a three element list containing the red,
  259.      green, and blue color components of COLOR-INSTANCE.
  260.  
  261.           (color-instance-rgb-components
  262.             (face-background-instance 'default (next-window)))
  263.               => (65535 58596 46517)
  264.  
  265. 
  266. File: lispref.info,  Node: Color Convenience Functions,  Prev: Color Instance Properties,  Up: Colors
  267.  
  268. Color Convenience Functions
  269. ---------------------------
  270.  
  271.  - Function: color-name COLOR &optional DOMAIN
  272.      This function returns the name of the COLOR in the specified
  273.      DOMAIN, if any.  COLOR should be a color specifier object and
  274.      DOMAIN is normally a window and defaults to the selected window if
  275.      omitted.  This is equivalent to using `specifier-instance' and
  276.      applying `color-instance-name' to the result.
  277.  
  278.  - Function: color-rgb-components COLOR &optional DOMAIN
  279.      This function returns the RGB components of the COLOR in the
  280.      specified DOMAIN, if any.  COLOR should be a color specifier
  281.      object and DOMAIN is normally a window and defaults to the
  282.      selected window if omitted.  This is equivalent to using
  283.      `specifier-instance' and applying `color-instance-rgb-components'
  284.      to the result.
  285.  
  286.           (color-rgb-components (face-background 'default (next-window)))
  287.               => (65535 58596 46517)
  288.  
  289. 
  290. File: lispref.info,  Node: Glyphs,  Next: Annotations,  Prev: Faces and Window-System Objects,  Up: Top
  291.  
  292. Glyphs
  293. ******
  294.  
  295.    A "glyph" is an object that is used for pixmaps and images of all
  296. sorts, as well as for things that "act" like pixmaps, such as
  297. non-textual strings ("annotations") displayed in a buffer or in the
  298. margins.  It is used in begin-glyphs and end-glyphs attached to extents,
  299. marginal and textual annotations, overlay arrows (`overlay-arrow-*'
  300. variables), toolbar buttons, mouse pointers, frame icons, truncation and
  301. continuation markers, and the like. (Basically, any place there is an
  302. image or something that acts like an image, there will be a glyph object
  303. representing it.)
  304.  
  305.    The actual image that is displayed (as opposed to its position or
  306. clipping) is defined by an "image specifier" object contained within
  307. the glyph.  The separation between an image specifier object and a
  308. glyph object is made because the glyph includes other properties than
  309. just the actual image: e.g. the face it is displayed in (for text
  310. images), the alignment of the image (when it is in a buffer), etc.
  311.  
  312.  - Function: glyphp OBJECT
  313.      This function returns `t' if OBJECT is a glyph.
  314.  
  315. * Menu:
  316.  
  317. * Glyph Functions::    Functions for working with glyphs.
  318. * Images::        Graphical images displayed in a frame.
  319. * Glyph Types::         Each glyph has a particular type.
  320. * Mouse Pointer::    Controlling the mouse pointer.
  321. * Redisplay Glyphs::    Glyphs controlling various redisplay functions.
  322. * Subwindows::          Inserting an externally-controlled subwindow
  323.                           into a buffer.
  324.  
  325. 
  326. File: lispref.info,  Node: Glyph Functions,  Next: Images,  Up: Glyphs
  327.  
  328. Glyph Functions
  329. ===============
  330.  
  331. * Menu:
  332.  
  333. * Creating Glyphs::    Creating new glyphs.
  334. * Glyph Properties::    Accessing and modifying a glyph's properties.
  335. * Glyph Convenience Functions::
  336.             Convenience functions for accessing particular
  337.               properties of a glyph.
  338. * Glyph Dimensions::    Determining the height, width, etc. of a glyph.
  339.  
  340. 
  341. File: lispref.info,  Node: Creating Glyphs,  Next: Glyph Properties,  Up: Glyph Functions
  342.  
  343. Creating Glyphs
  344. ---------------
  345.  
  346.  - Function: make-glyph &optional SPEC-LIST TYPE
  347.      This function creates a new glyph object of type TYPE.
  348.  
  349.      SPEC-LIST is used to initialize the glyph's image.  It is
  350.      typically an image instantiator (a string or a vector; *Note Image
  351.      Specifiers::), but can also be a list of such instantiators (each
  352.      one in turn is tried until an image is successfully produced), a
  353.      cons of a locale (frame, buffer, etc.) and an instantiator, a list
  354.      of such conses, or any other form accepted by
  355.      `canonicalize-spec-list'.  *Note Specifiers:: for more information
  356.      about specifiers.
  357.  
  358.      TYPE specifies the type of the glyph, which specifies in which
  359.      contexts the glyph can be used, and controls the allowable image
  360.      types into which the glyph's image can be instantiated.  TYPE
  361.      should be one of `buffer' (used for glyphs in an extent, the
  362.      modeline, the toolbar, or elsewhere in a buffer), `pointer' (used
  363.      for the mouse-pointer), or `icon' (used for a frame's icon), and
  364.      defaults to `buffer'.  *Note Glyph Types::.
  365.  
  366.  - Function: make-glyph-internal &optional TYPE
  367.      This function creates a new, uninitialized glyph of type TYPE.
  368.  
  369.  - Function: make-pointer-glyph &optional SPEC-LIST
  370.      This function is equivalent to calling `make-glyph' with a TYPE of
  371.      `pointer'.
  372.  
  373.  - Function: make-icon-glyph &optional SPEC-LIST
  374.      This function is equivalent to calling `make-glyph' with a TYPE of
  375.      `icon'.
  376.  
  377. 
  378. File: lispref.info,  Node: Glyph Properties,  Next: Glyph Convenience Functions,  Prev: Creating Glyphs,  Up: Glyph Functions
  379.  
  380. Glyph Properties
  381. ----------------
  382.  
  383.    Each glyph has a list of properties, which control all of the
  384. aspects of the glyph's appearance.  The following symbols have
  385. predefined meanings:
  386.  
  387. `image'
  388.      The image used to display the glyph.
  389.  
  390. `baseline'
  391.      Percent above baseline that glyph is to be displayed.  Only for
  392.      glyphs displayed inside of a buffer.
  393.  
  394. `contrib-p'
  395.      Whether the glyph contributes to the height of the line it's on.
  396.      Only for glyphs displayed inside of a buffer.
  397.  
  398. `face'
  399.      Face of this glyph (*not* a specifier).
  400.  
  401.  - Function: set-glyph-property GLYPH PROPERTY VALUE &optional LOCALE
  402.           TAG-SET HOW-TO-ADD
  403.      This function changes a property of a GLYPH.
  404.  
  405.      For built-in properties, the actual value of the property is a
  406.      specifier and you cannot change this; but you can change the
  407.      specifications within the specifier, and that is what this
  408.      function will do.  For user-defined properties, you can use this
  409.      function to either change the actual value of the property or, if
  410.      this value is a specifier, change the specifications within it.
  411.  
  412.      If PROPERTY is a built-in property, the specifications to be added
  413.      to this property can be supplied in many different ways:
  414.  
  415.         * If VALUE is a simple instantiator (e.g. a string naming a
  416.           pixmap filename) or a list of instantiators, then the
  417.           instantiator(s) will be added as a specification of the
  418.           property for the given LOCALE (which defaults to `global' if
  419.           omitted).
  420.  
  421.         * If VALUE is a list of specifications (each of which is a cons
  422.           of a locale and a list of instantiators), then LOCALE must be
  423.           `nil' (it does not make sense to explicitly specify a locale
  424.           in this case), and specifications will be added as given.
  425.  
  426.         * If VALUE is a specifier (as would be returned by
  427.           `glyph-property' if no LOCALE argument is given), then some
  428.           or all of the specifications in the specifier will be added
  429.           to the property.  In this case, the function is really
  430.           equivalent to `copy-specifier' and LOCALE has the same
  431.           semantics (if it is a particular locale, the specification
  432.           for the locale will be copied; if a locale type,
  433.           specifications for all locales of that type will be copied;
  434.           if `nil' or `all', then all specifications will be copied).
  435.  
  436.      HOW-TO-ADD should be either `nil' or one of the symbols `prepend',
  437.      `append', `remove-tag-set-prepend', `remove-tag-set-append',
  438.      `remove-locale', `remove-locale-type', or `remove-all'.  See
  439.      `copy-specifier' and `add-spec-to-specifier' for a description of
  440.      what each of these means.  Most of the time, you do not need to
  441.      worry about this argument; the default behavior usually is fine.
  442.  
  443.      In general, it is OK to pass an instance object (e.g. as returned
  444.      by `glyph-property-instance') as an instantiator in place of an
  445.      actual instantiator.  In such a case, the instantiator used to
  446.      create that instance object will be used (for example, if you set
  447.      a font-instance object as the value of the `font' property, then
  448.      the font name used to create that object will be used instead).
  449.      If some cases, however, doing this conversion does not make sense,
  450.      and this will be noted in the documentation for particular types
  451.      of instance objects.
  452.  
  453.      If PROPERTY is not a built-in property, then this function will
  454.      simply set its value if LOCALE is `nil'.  However, if LOCALE is
  455.      given, then this function will attempt to add VALUE as the
  456.      instantiator for the given LOCALE, using `add-spec-to-specifier'.
  457.      If the value of the property is not a specifier, it will
  458.      automatically be converted into a `generic' specifier.
  459.  
  460.  - Function: glyph-property GLYPH PROPERTY &optional LOCALE
  461.      This function returns GLYPH's value of the given PROPERTY.
  462.  
  463.      If LOCALE is omitted, the GLYPH's actual value for PROPERTY will
  464.      be returned.  For built-in properties, this will be a specifier
  465.      object of a type appropriate to the property (e.g. a font or color
  466.      specifier).  For other properties, this could be anything.
  467.  
  468.      If LOCALE is supplied, then instead of returning the actual value,
  469.      the specification(s) for the given locale or locale type will be
  470.      returned.  This will only work if the actual value of PROPERTY is
  471.      a specifier (this will always be the case for built-in properties,
  472.      but may or may not apply to user-defined properties).  If the
  473.      actual value of PROPERTY is not a specifier, this value will
  474.      simply be returned regardless of LOCALE.
  475.  
  476.      The return value will be a list of instantiators (e.g. vectors
  477.      specifying pixmap data), or a list of specifications, each of
  478.      which is a cons of a locale and a list of instantiators.
  479.      Specifically, if LOCALE is a particular locale (a buffer, window,
  480.      frame, device, or `global'), a list of instantiators for that
  481.      locale will be returned.  Otherwise, if LOCALE is a locale type
  482.      (one of the symbols `buffer', `window', `frame', or `device'), the
  483.      specifications for all locales of that type will be returned.
  484.      Finally, if LOCALE is `all', the specifications for all locales of
  485.      all types will be returned.
  486.  
  487.      The specifications in a specifier determine what the value of
  488.      PROPERTY will be in a particular "domain" or set of circumstances,
  489.      which is typically a particular Emacs window along with the buffer
  490.      it contains and the frame and device it lies within.  The value is
  491.      derived from the instantiator associated with the most specific
  492.      locale (in the order buffer, window, frame, device, and `global')
  493.      that matches the domain in question.  In other words, given a
  494.      domain (i.e. an Emacs window, usually), the specifier for PROPERTY
  495.      will first be searched for a specification whose locale is the
  496.      buffer contained within that window; then for a specification
  497.      whose locale is the window itself; then for a specification whose
  498.      locale is the frame that the window is contained within; etc.  The
  499.      first instantiator that is valid for the domain (usually this
  500.      means that the instantiator is recognized by the device [i.e. the
  501.      X server or TTY device] that the domain is on).  The function
  502.      `glyph-property-instance' actually does all this, and is used to
  503.      determine how to display the glyph.
  504.  
  505.  - Function: glyph-property-instance GLYPH PROPERTY &optional DOMAIN
  506.           DEFAULT NO-FALLBACK
  507.      This function returns the instance of GLYPH's PROPERTY in the
  508.      specified DOMAIN.
  509.  
  510.      Under most circumstances, DOMAIN will be a particular window, and
  511.      the returned instance describes how the specified property
  512.      actually is displayed for that window and the particular buffer in
  513.      it.  Note that this may not be the same as how the property
  514.      appears when the buffer is displayed in a different window or
  515.      frame, or how the property appears in the same window if you
  516.      switch to another buffer in that window; and in those cases, the
  517.      returned instance would be different.
  518.  
  519.      The returned instance is an image-instance object, and you can
  520.      query it using the appropriate image instance functions.  For
  521.      example, you could use `image-instance-depth' to find out the
  522.      depth (number of color planes) of a pixmap displayed in a
  523.      particular window.  The results might be different from the
  524.      results you would get for another window (perhaps the user
  525.      specified a different image for the frame that window is on; or
  526.      perhaps the same image was specified but the window is on a
  527.      different X server, and that X server has different color
  528.      capabilities from this one).
  529.  
  530.      DOMAIN defaults to the selected window if omitted.
  531.  
  532.      DOMAIN can be a frame or device, instead of a window.  The value
  533.      returned for such a domain is used in special circumstances when a
  534.      more specific domain does not apply; for example, a frame value
  535.      might be used for coloring a toolbar, which is conceptually
  536.      attached to a frame rather than a particular window.  The value is
  537.      also useful in determining what the value would be for a
  538.      particular window within the frame or device, if it is not
  539.      overridden by a more specific specification.
  540.  
  541.      If PROPERTY does not name a built-in property, its value will
  542.      simply be returned unless it is a specifier object, in which case
  543.      it will be instanced using `specifier-instance'.
  544.  
  545.      Optional arguments DEFAULT and NO-FALLBACK are the same as in
  546.      `specifier-instance'.  *Note Specifiers::.
  547.  
  548.  - Function: remove-glyph-property GLYPH PROPERTY &optional LOCALE
  549.           TAG-SET EXACT-P
  550.      This function removes a property from a glyph.  For built-in
  551.      properties, this is analogous to `remove-specifier'.  *Note
  552.      remove-specifier-p: Specifiers, for the meaning of the LOCALE,
  553.      TAG-SET, and EXACT-P arguments.
  554.  
  555. 
  556. File: lispref.info,  Node: Glyph Convenience Functions,  Next: Glyph Dimensions,  Prev: Glyph Properties,  Up: Glyph Functions
  557.  
  558. Glyph Convenience Functions
  559. ---------------------------
  560.  
  561.    The following functions are provided for working with specific
  562. properties of a glyph.  Note that these are exactly like calling the
  563. general functions described above and passing in the appropriate value
  564. for PROPERTY.
  565.  
  566.    Remember that if you want to determine the "value" of a specific
  567. glyph property, you probably want to use the `*-instance' functions.
  568. For example, to determine whether a glyph contributes to its line
  569. height, use `glyph-contrib-p-instance', not `glyph-contrib-p'. (The
  570. latter will return a boolean specifier or a list of specifications, and
  571. you probably aren't concerned with these.)
  572.  
  573.  - Function: glyph-image GLYPH &optional LOCALE
  574.      This function is equivalent to calling `glyph-property' with a
  575.      property of `image'.  The return value will be an image specifier
  576.      if LOCALE is `nil' or omitted; otherwise, it will be a
  577.      specification or list of specifications.
  578.  
  579.  - Function: set-glyph-image GLYPH SPEC &optional LOCALE TAG-SET
  580.           HOW-TO-ADD
  581.      This function is equivalent to calling `set-glyph-property' with a
  582.      property of `image'.
  583.  
  584.  - Function: glyph-image-instance GLYPH &optional DOMAIN DEFAULT
  585.           NO-FALLBACK
  586.      This function returns the instance of GLYPH's image in the given
  587.      DOMAIN, and is equivalent to calling `glyph-property-instance'
  588.      with a property of `image'.  The return value will be an image
  589.      instance.
  590.  
  591.      Normally DOMAIN will be a window or `nil' (meaning the selected
  592.      window), and an instance object describing how the image appears
  593.      in that particular window and buffer will be returned.
  594.  
  595.  - Function: glyph-contrib-p GLYPH &optional LOCALE
  596.      This function is equivalent to calling `glyph-property' with a
  597.      property of `contrib-p'.  The return value will be a boolean
  598.      specifier if LOCALE is `nil' or omitted; otherwise, it will be a
  599.      specification or list of specifications.
  600.  
  601.  - Function: set-glyph-contrib-p GLYPH SPEC &optional LOCALE TAG-SET
  602.           HOW-TO-ADD
  603.      This function is equivalent to calling `set-glyph-property' with a
  604.      property of `contrib-p'.
  605.  
  606.  - Function: glyph-contrib-p-instance GLYPH &optional DOMAIN DEFAULT
  607.           NO-FALLBACK
  608.      This function returns whether the glyph contributes to its line
  609.      height in the given DOMAIN, and is equivalent to calling
  610.      `glyph-property-instance' with a property of `contrib-p'.  The
  611.      return value will be either `nil' or `t'. (Normally DOMAIN will be
  612.      a window or `nil', meaning the selected window.)
  613.  
  614.  - Function: glyph-baseline GLYPH &optional LOCALE
  615.      This function is equivalent to calling `glyph-property' with a
  616.      property of `baseline'.  The return value will be a specifier if
  617.      LOCALE is `nil' or omitted; otherwise, it will be a specification
  618.      or list of specifications.
  619.  
  620.  - Function: set-glyph-baseline GLYPH SPEC &optional LOCALE TAG-SET
  621.           HOW-TO-ADD
  622.      This function is equivalent to calling `set-glyph-property' with a
  623.      property of `baseline'.
  624.  
  625.  - Function: glyph-baseline-instance GLYPH &optional DOMAIN DEFAULT
  626.           NO-FALLBACK
  627.      This function returns the instance of GLYPH's baseline value in
  628.      the given DOMAIN, and is equivalent to calling
  629.      `glyph-property-instance' with a property of `baseline'.  The
  630.      return value will be an integer or `nil'.
  631.  
  632.      Normally DOMAIN will be a window or `nil' (meaning the selected
  633.      window), and an instance object describing the baseline value
  634.      appears in that particular window and buffer will be returned.
  635.  
  636.  - Function: glyph-face GLYPH
  637.      This function returns the face of GLYPH. (Remember, this is not a
  638.      specifier, but a simple property.)
  639.  
  640.  - Function: set-glyph-face GLYPH FACE
  641.      This function changes the face of GLYPH to FACE.
  642.  
  643. 
  644. File: lispref.info,  Node: Glyph Dimensions,  Prev: Glyph Convenience Functions,  Up: Glyph Functions
  645.  
  646. Glyph Dimensions
  647. ----------------
  648.  
  649.  - Function: glyph-width GLYPH &optional WINDOW
  650.      This function returns the width of GLYPH on WINDOW.  This may not
  651.      be exact as it does not take into account all of the context that
  652.      redisplay will.
  653.  
  654.  - Function: glyph-ascent GLYPH &optional WINDOW
  655.      This function returns the ascent value of GLYPH on WINDOW.  This
  656.      may not be exact as it does not take into account all of the
  657.      context that redisplay will.
  658.  
  659.  - Function: glyph-descent GLYPH &optional WINDOW
  660.      This function returns the descent value of GLYPH on WINDOW.  This
  661.      may not be exact as it does not take into account all of the
  662.      context that redisplay will.
  663.  
  664.  - Function: glyph-height GLYPH &optional WINDOW
  665.      This function returns the height of GLYPH on WINDOW.  (This is
  666.      equivalent to the sum of the ascent and descent values.)  This may
  667.      not be exact as it does not take into account all of the context
  668.      that redisplay will.
  669.  
  670. 
  671. File: lispref.info,  Node: Images,  Next: Glyph Types,  Prev: Glyph Functions,  Up: Glyphs
  672.  
  673. Images
  674. ======
  675.  
  676. * Menu:
  677.  
  678. * Image Specifiers::        Specifying how an image will appear.
  679. * Image Instantiator Conversion::
  680.                 Conversion is applied to image instantiators
  681.                   at the time they are added to an
  682.                   image specifier or at the time they
  683.                   are passed to `make-image-instance'.
  684. * Image Instances::        What an image specifier gets instanced as.
  685.  
  686. 
  687. File: lispref.info,  Node: Image Specifiers,  Next: Image Instantiator Conversion,  Up: Images
  688.  
  689. Image Specifiers
  690. ----------------
  691.  
  692.    An image specifier is used to describe the actual image of a glyph.
  693. It works like other specifiers (*note Specifiers::.), in that it
  694. contains a number of specifications describing how the image should
  695. appear in a variety of circumstances.  These specifications are called
  696. "image instantiators".  When XEmacs wants to display the image, it
  697. instantiates the image into an "image instance".  Image instances are
  698. their own primitive object type (similar to font instances and color
  699. instances), describing how the image appears in a particular domain.
  700. (On the other hand, image instantiators, which are just descriptions of
  701. how the image should appear, are represented using strings or vectors.)
  702.  
  703.  - Function: image-specifier-p OBJECT
  704.      This function returns non-`nil' if OBJECT is an image specifier.
  705.      Usually, an image specifier results from calling `glyph-image' on
  706.      a glyph.
  707.  
  708.  - Function: make-image-specifier SPEC-LIST
  709.      This function creates a new image specifier object and initializes
  710.      it according to SPEC-LIST.  It is unlikely that you will ever want
  711.      to do this, but this function is provided for completeness and for
  712.      experimentation purposes.  *Note Specifiers::.
  713.  
  714.    Image instantiators come in many formats: `xbm', `xpm', `gif',
  715. `jpeg', etc.  This describes the format of the data describing the
  716. image.  The resulting image instances also come in many types -
  717. `mono-pixmap', `color-pixmap', `text', `pointer', etc.  This refers to
  718. the behavior of the image and the sorts of places it can appear. (For
  719. example, a color-pixmap image has fixed colors specified for it, while
  720. a mono-pixmap image comes in two unspecified shades "foreground" and
  721. "background" that are determined from the face of the glyph or
  722. surrounding text; a text image appears as a string of text and has an
  723. unspecified foreground, background, and font; a pointer image behaves
  724. like a mono-pixmap image but can only be used as a mouse pointer
  725. [mono-pixmap images cannot be used as mouse pointers]; etc.) It is
  726. important to keep the distinction between image instantiator format and
  727. image instance type in mind.  Typically, a given image instantiator
  728. format can result in many different image instance types (for example,
  729. `xpm' can be instanced as `color-pixmap', `mono-pixmap', or `pointer';
  730. whereas `cursor-font' can be instanced only as `pointer'), and a
  731. particular image instance type can be generated by many different image
  732. instantiator formats (e.g.  `color-pixmap' can be generated by `xpm',
  733. `gif', `jpeg', etc.).
  734.  
  735.    *Note Image Instances:: for a more detailed discussion of image
  736. instance types.
  737.  
  738.    An image instantiator should be a string or a vector of the form
  739.  
  740.       `[FORMAT :KEYWORD VALUE ...]'
  741.  
  742.    i.e. a format symbol followed by zero or more alternating
  743. keyword-value pairs.  The "format" field should be a symbol, one of
  744.  
  745. `nothing'
  746.      (Don't display anything; no keywords are valid for this.  Can only
  747.      be instanced as `nothing'.)
  748.  
  749. `string'
  750.      (Display this image as a text string.  Can only be instanced as
  751.      `text', although support for instancing as `mono-pixmap' should be
  752.      added.)
  753.  
  754. `formatted-string'
  755.      (Display this image as a text string with replaceable fields,
  756.      similar to a modeline format string; not currently implemented.)
  757.  
  758. `xbm'
  759.      (An X bitmap; only if X support was compiled into this XEmacs.
  760.      Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
  761.  
  762. `xpm'
  763.      (An XPM pixmap; only if XPM support was compiled into this XEmacs.
  764.      Can be instanced as `color-pixmap', `mono-pixmap', or `pointer'.
  765.      XPM is an add-on library for X that was designed to rectify the
  766.      shortcomings of the XBM format.  Most implementations of X include
  767.      the XPM library as a standard part.  If your vendor does not, it
  768.      is highly recommended that you download it and install it.  You
  769.      can get it from the standard XEmacs FTP site, among other places.)
  770.  
  771. `xface'
  772.      (An X-Face bitmap, used to encode people's faces in e-mail
  773.      messages; only if X-Face support was compiled into this XEmacs.
  774.      Can be instanced as `mono-pixmap', `color-pixmap', or `pointer'.)
  775.  
  776. `gif'
  777.      (A GIF87 or GIF89 image; only if GIF support was compiled into this
  778.      XEmacs.  Can be instanced as `color-pixmap'.  Note that XEmacs
  779.      includes GIF decoding functions as a standard part of it, so if
  780.      you have X support, you will normally have GIF support, unless you
  781.      explicitly disable it at configure time.)
  782.  
  783. `jpeg'
  784.      (A JPEG-format image; only if JPEG support was compiled into this
  785.      XEmacs.  Can be instanced as `color-pixmap'.  If you have the JPEG
  786.      libraries present on your system when XEmacs is built, XEmacs will
  787.      automatically detect this and use them, unless you explicitly
  788.      disable it at configure time.)
  789.  
  790. `png'
  791.      (A PNG/GIF24 image; only if PNG support was compiled into this
  792.      XEmacs.  Can be instanced as `color-pixmap'.)
  793.  
  794. `tiff'
  795.      (A TIFF-format image; only if TIFF support was compiled into this
  796.      XEmacs.  Not currently implemented.)
  797.  
  798. `cursor-font'
  799.      (One of the standard cursor-font names, such as `watch' or
  800.      `right_ptr' under X.  Under X, this is, more specifically, any of
  801.      the standard cursor names from appendix B of the Xlib manual [also
  802.      known as the file `<X11/cursorfont.h>'] minus the `XC_' prefix.  On
  803.      other window systems, the valid names will be specific to the type
  804.      of window system.  Can only be instanced as `pointer'.)
  805.  
  806. `font'
  807.      (A glyph from a font; i.e. the name of a font, and glyph index
  808.      into it of the form `FONT fontname index [[mask-font] mask-index]'.
  809.      Only if X support was compiled into this XEmacs.  Currently can
  810.      only be instanced as `pointer', although this should probably be
  811.      fixed.)
  812.  
  813. `subwindow'
  814.      (An embedded X window; not currently implemented.)
  815.  
  816. `autodetect'
  817.      (XEmacs tries to guess what format the data is in.  If X support
  818.      exists, the data string will be checked to see if it names a
  819.      filename.  If so, and this filename contains XBM or XPM data, the
  820.      appropriate sort of pixmap or pointer will be created. [This
  821.      includes picking up any specified hotspot or associated mask
  822.      file.] Otherwise, if `pointer' is one of the allowable
  823.      image-instance types and the string names a valid cursor-font
  824.      name, the image will be created as a pointer.  Otherwise, the
  825.      image will be displayed as text.  If no X support exists, the
  826.      image will always be displayed as text.)
  827.  
  828.    The valid keywords are:
  829.  
  830. `:data'
  831.      (Inline data.  For most formats above, this should be a string.
  832.      For XBM images, this should be a list of three elements: width,
  833.      height, and a string of bit data.  This keyword is not valid for
  834.      instantiator format `nothing'.)
  835.  
  836. `:file'
  837.      (Data is contained in a file.  The value is the name of this file.
  838.      If both `:data' and `:file' are specified, the image is created
  839.      from what is specified in `:data' and the string in `:file'
  840.      becomes the value of the `image-instance-file-name' function when
  841.      applied to the resulting image-instance.  This keyword is not
  842.      valid for instantiator formats `nothing', `string',
  843.      `formatted-string', `cursor-font', `font', and `autodetect'.)
  844.  
  845. `:foreground'
  846. `:background'
  847.      (For `xbm', `xface', `cursor-font', and `font'.  These keywords
  848.      allow you to explicitly specify foreground and background colors.
  849.      The argument should be anything acceptable to
  850.      `make-color-instance'.  This will cause what would be a
  851.      `mono-pixmap' to instead be colorized as a two-color color-pixmap,
  852.      and specifies the foreground and/or background colors for a pointer
  853.      instead of black and white.)
  854.  
  855. `:mask-data'
  856.      (For `xbm' and `xface'.  This specifies a mask to be used with the
  857.      bitmap.  The format is a list of width, height, and bits, like for
  858.      `:data'.)
  859.  
  860. `:mask-file'
  861.      (For `xbm' and `xface'.  This specifies a file containing the mask
  862.      data.  If neither a mask file nor inline mask data is given for an
  863.      XBM image, and the XBM image comes from a file, XEmacs will look
  864.      for a mask file with the same name as the image file but with
  865.      `Mask' or `msk' appended.  For example, if you specify the XBM file
  866.      `left_ptr' [usually located in `/usr/include/X11/bitmaps'], the
  867.      associated mask file `left_ptrmsk' will automatically be picked
  868.      up.)
  869.  
  870. `:hotspot-x'
  871. `:hotspot-y'
  872.      (For `xbm' and `xface'.  These keywords specify a hotspot if the
  873.      image is instantiated as a `pointer'.  Note that if the XBM image
  874.      file specifies a hotspot, it will automatically be picked up if no
  875.      explicit hotspot is given.)
  876.  
  877. `:color-symbols'
  878.      (Only for `xpm'.  This specifies an alist that maps strings that
  879.      specify symbolic color names to the actual color to be used for
  880.      that symbolic color (in the form of a string or a color-specifier
  881.      object).  If this is not specified, the contents of
  882.      `xpm-color-symbols' are used to generate the alist.)
  883.  
  884.    If instead of a vector, the instantiator is a string, it will be
  885. converted into a vector by looking it up according to the specs in the
  886. `console-type-image-conversion-list' for the console type of the domain
  887. (usually a window; sometimes a frame or device) over which the image is
  888. being instantiated.
  889.  
  890.    If the instantiator specifies data from a file, the data will be
  891. read in at the time that the instantiator is added to the image
  892. specifier (which may be well before the image is actually displayed),
  893. and the instantiator will be converted into one of the inline-data
  894. forms, with the filename retained using a `:file' keyword.  This
  895. implies that the file must exist when the instantiator is added to the
  896. image, but does not need to exist at any other time (e.g. it may safely
  897. be a temporary file).
  898.  
  899.  - Function: valid-image-instantiator-format-p FORMAT
  900.      This function returns non-`nil' if FORMAT is a valid image
  901.      instantiator format.  Note that the return value for many formats
  902.      listed above depends on whether XEmacs was compiled with support
  903.      for that format.
  904.  
  905.  - Function: image-instantiator-format-list
  906.      This function return a list of valid image-instantiator formats.
  907.  
  908.  - Variable: xpm-color-symbols
  909.      This variable holds definitions of logical color-names used when
  910.      reading XPM files.  Elements of this list should be of the form
  911.      `(COLOR-NAME FORM-TO-EVALUATE)'.  The COLOR-NAME should be a
  912.      string, which is the name of the color to define; the
  913.      FORM-TO-EVALUATE should evaluate to a color specifier object, or a
  914.      string to be passed to `make-color-instance' (*note Colors::.).  If
  915.      a loaded XPM file references a symbolic color called COLOR-NAME,
  916.      it will display as the computed color instead.
  917.  
  918.      The default value of this variable defines the logical color names
  919.      `"foreground"' and `"background"' to be the colors of the
  920.      `default' face.
  921.  
  922.  - Variable: x-bitmap-file-path
  923.      A list of the directories in which X bitmap files may be found.
  924.      If nil, this is initialized from the `"*bitmapFilePath"' resource.
  925.      This is used by the `make-image-instance' function (however, note
  926.      that if the environment variable `XBMLANGPATH' is set, it is
  927.      consulted first).
  928.  
  929. 
  930. File: lispref.info,  Node: Image Instantiator Conversion,  Next: Image Instances,  Prev: Image Specifiers,  Up: Images
  931.  
  932. Image Instantiator Conversion
  933. -----------------------------
  934.  
  935.  - Function: set-console-type-image-conversion-list CONSOLE-TYPE LIST
  936.      This function sets the image-conversion-list for consoles of the
  937.      given CONSOLE-TYPE.  The image-conversion-list specifies how image
  938.      instantiators that are strings should be interpreted.  Each
  939.      element of the list should be a list of two elements (a regular
  940.      expression string and a vector) or a list of three elements (the
  941.      preceding two plus an integer index into the vector).  The string
  942.      is converted to the vector associated with the first matching
  943.      regular expression.  If a vector index is specified, the string
  944.      itself is substituted into that position in the vector.
  945.  
  946.      Note: The conversion above is applied when the image instantiator
  947.      is added to an image specifier, not when the specifier is actually
  948.      instantiated.  Therefore, changing the image-conversion-list only
  949.      affects newly-added instantiators.  Existing instantiators in
  950.      glyphs and image specifiers will not be affected.
  951.  
  952.  - Function: console-type-image-conversion-list CONSOLE-TYPE
  953.      This function returns the image-conversion-list for consoles of
  954.      the given CONSOLE-TYPE.
  955.  
  956. 
  957. File: lispref.info,  Node: Image Instances,  Prev: Image Instantiator Conversion,  Up: Images
  958.  
  959. Image Instances
  960. ---------------
  961.  
  962.    Image-instance objects encapsulate the way a particular image
  963. (pixmap, etc.) is displayed on a particular device.
  964.  
  965.    In most circumstances, you do not need to directly create image
  966. instances; use a glyph instead.  However, it may occasionally be useful
  967. to explicitly create image instances, if you want more control over the
  968. instantiation process.
  969.  
  970.  - Function: image-instance-p OBJECT
  971.      This function returns non-`nil' if OBJECT is an image instance.
  972.  
  973. * Menu:
  974.  
  975. * Image Instance Types::         Each image instances has a particular type.
  976. * Image Instance Functions::     Functions for working with image instances.
  977.  
  978. 
  979. File: lispref.info,  Node: Image Instance Types,  Next: Image Instance Functions,  Up: Image Instances
  980.  
  981. Image Instance Types
  982. ....................
  983.  
  984.    Image instances come in a number of different types.  The type of an
  985. image instance specifies the nature of the image: Whether it is a text
  986. string, a mono pixmap, a color pixmap, etc.
  987.  
  988.    The valid image instance types are
  989.  
  990. `nothing'
  991.      Nothing is displayed.
  992.  
  993. `text'
  994.      Displayed as text.  The foreground and background colors and the
  995.      font of the text are specified independent of the pixmap.
  996.      Typically these attributes will come from the face of the
  997.      surrounding text, unless a face is specified for the glyph in
  998.      which the image appears.
  999.  
  1000. `mono-pixmap'
  1001.      Displayed as a mono pixmap (a pixmap with only two colors where the
  1002.      foreground and background can be specified independent of the
  1003.      pixmap; typically the pixmap assumes the foreground and background
  1004.      colors of the text around it, unless a face is specified for the
  1005.      glyph in which the image appears).
  1006.  
  1007. `color-pixmap'
  1008.      Displayed as a color pixmap.
  1009.  
  1010. `pointer'
  1011.      Used as the mouse pointer for a window.
  1012.  
  1013. `subwindow'
  1014.      A child window that is treated as an image.  This allows (e.g.)
  1015.      another program to be responsible for drawing into the window.
  1016.      Not currently implemented.
  1017.  
  1018.  - Function: valid-image-instance-type-p TYPE
  1019.      This function returns non-`nil' if TYPE is a valid image instance
  1020.      type.
  1021.  
  1022.  - Function: image-instance-type-list
  1023.      This function returns a list of the valid image instance types.
  1024.  
  1025.  - Function: image-instance-type IMAGE-INSTANCE
  1026.      This function returns the type of the given image instance.  The
  1027.      return value will be one of `nothing', `text', `mono-pixmap',
  1028.      `color-pixmap', `pointer', or `subwindow'.
  1029.  
  1030.  - Function: text-image-instance-p OBJECT
  1031.      This function returns non-`nil' if OBJECT is an image instance of
  1032.      type `text'.
  1033.  
  1034.  - Function: mono-pixmap-image-instance-p OBJECT
  1035.      This function returns non-`nil' if OBJECT is an image instance of
  1036.      type `mono-pixmap'.
  1037.  
  1038.  - Function: color-pixmap-image-instance-p OBJECT
  1039.      This function returns non-`nil' if OBJECT is an image instance of
  1040.      type `color-pixmap'.
  1041.  
  1042.  - Function: pointer-image-instance-p OBJECT
  1043.      This function returns non-`nil' if OBJECT is an image instance of
  1044.      type `pointer'.
  1045.  
  1046.  - Function: subwindow-image-instance-p OBJECT
  1047.      This function returns non-`nil' if OBJECT is an image instance of
  1048.      type `subwindow'.
  1049.  
  1050.  - Function: nothing-image-instance-p OBJECT
  1051.      This function returns non-`nil' if OBJECT is an image instance of
  1052.      type `nothing'.
  1053.  
  1054. 
  1055. File: lispref.info,  Node: Image Instance Functions,  Prev: Image Instance Types,  Up: Image Instances
  1056.  
  1057. Image Instance Functions
  1058. ........................
  1059.  
  1060.  - Function: make-image-instance DATA &optional DEVICE DEST-TYPES
  1061.           NO-ERROR
  1062.      This function creates a new image-instance object.
  1063.  
  1064.      DATA is an image instantiator, which describes the image (*note
  1065.      Image Specifiers::.).
  1066.  
  1067.      DEST-TYPES should be a list of allowed image instance types that
  1068.      can be generated.  The DEST-TYPES list is unordered.  If multiple
  1069.      destination types are possible for a given instantiator, the "most
  1070.      natural" type for the instantiator's format is chosen. (For XBM,
  1071.      the most natural types are `mono-pixmap', followed by
  1072.      `color-pixmap', followed by `pointer'.  For the other normal image
  1073.      formats, the most natural types are `color-pixmap', followed by
  1074.      `mono-pixmap', followed by `pointer'.  For the string and
  1075.      formatted-string formats, the most natural types are `text',
  1076.      followed by `mono-pixmap' (not currently implemented), followed by
  1077.      `color-pixmap' (not currently implemented).  The other formats can
  1078.      only be instantiated as one type. (If you want to control more
  1079.      specifically the order of the types into which an image is
  1080.      instantiated, just call `make-image-instance' repeatedly until it
  1081.      succeeds, passing less and less preferred destination types each
  1082.      time.
  1083.  
  1084.      If DEST-TYPES is omitted, all possible types are allowed.
  1085.  
  1086.      NO-ERROR controls what happens when the image cannot be generated.
  1087.      If NIL, an error message is generated.  If T, no messages are
  1088.      generated and this function returns NIL.  If anything else, a
  1089.      warning message is generated and this function returns NIL.
  1090.  
  1091.  - Function: colorize-image-instance IMAGE-INSTANCE FOREGROUND
  1092.           BACKGROUND
  1093.      This function makes the image instance be displayed in the given
  1094.      colors.  Image instances come in two varieties: bitmaps, which are
  1095.      1 bit deep which are rendered in the prevailing foreground and
  1096.      background colors; and pixmaps, which are of arbitrary depth
  1097.      (including 1) and which have the colors explicitly specified.
  1098.      This function converts a bitmap to a pixmap.  If the image
  1099.      instance was a pixmap already, nothing is done (and `nil' is
  1100.      returned).  Otherwise `t' is returned.
  1101.  
  1102.  - Function: image-instance-name IMAGE-INSTANCE
  1103.      This function returns the name of the given image instance.
  1104.  
  1105.  - Function: image-instance-string IMAGE-INSTANCE
  1106.      This function returns the string of the given image instance.
  1107.      This will only be non-`nil' for text image instances.
  1108.  
  1109.  - Function: image-instance-file-name IMAGE-INSTANCE
  1110.      This function returns the file name from which IMAGE-INSTANCE was
  1111.      read, if known.
  1112.  
  1113.  - Function: image-instance-mask-file-name IMAGE-INSTANCE
  1114.      This function returns the file name from which IMAGE-INSTANCE's
  1115.      mask was read, if known.
  1116.  
  1117.  - Function: image-instance-depth IMAGE-INSTANCE
  1118.      This function returns the depth of the image instance.  This is 0
  1119.      for a mono pixmap, or a positive integer for a color pixmap.
  1120.  
  1121.  - Function: image-instance-height IMAGE-INSTANCE
  1122.      This function returns the height of the image instance, in pixels.
  1123.  
  1124.  - Function: image-instance-width IMAGE-INSTANCE
  1125.      This function returns the width of the image instance, in pixels.
  1126.  
  1127.  - Function: image-instance-hotspot-x IMAGE-INSTANCE
  1128.      This function returns the X coordinate of the image instance's
  1129.      hotspot, if known.  This is a point relative to the origin of the
  1130.      pixmap.  When an image is used as a mouse pointer, the hotspot is
  1131.      the point on the image that sits over the location that the
  1132.      pointer points to.  This is, for example, the tip of the arrow or
  1133.      the center of the crosshairs.
  1134.  
  1135.      This will always be `nil' for a non-pointer image instance.
  1136.  
  1137.  - Function: image-instance-hotspot-y IMAGE-INSTANCE
  1138.      This function returns the Y coordinate of the image instance's
  1139.      hotspot, if known.
  1140.  
  1141.  - Function: image-instance-foreground IMAGE-INSTANCE
  1142.      This function returns the foreground color of IMAGE-INSTANCE, if
  1143.      applicable.  This will be a color instance or `nil'. (It will only
  1144.      be non-`nil' for colorized mono pixmaps and for pointers.)
  1145.  
  1146.  - Function: image-instance-background IMAGE-INSTANCE
  1147.      This function returns the background color of IMAGE-INSTANCE, if
  1148.      applicable.  This will be a color instance or `nil'. (It will only
  1149.      be non-`nil' for colorized mono pixmaps and for pointers.)
  1150.  
  1151.